Inside Macintosh: QuickTime Components
| Previous | Chapter contents | Chapter top | Section top | Next |
Inside Macintosh: QuickTime Components
| Previous | Chapter contents | Chapter top | Section top | Next |
Your component may provide one or more configuration functions. These functions allow applications to configure your component before the Movie Toolbox calls your component to start the import process. Note that applications may call these functions directly.
All of these functions are optional. If your component receives a request that it does not support, you should return the badComponentSelector error code. In addition, your component should work properly even if none of these functions is called.
These functions address a variety of configuration issues. The MovieImportSetSampleDuration function allows an application to set your component's sample duration. Use the MovieImportSetDuration function to control the duration of the imported data. Applications can use the MovieImportSetDimensions function to specify the spatial dimensions of a new track. Use the MovieImportSetSampleDescription function to supply a sample description structure to your movie data import component.
The MovieImportSetMediaFile function allows applications to direct your component's output to a specific media file. Applications can provide additional data to your component by calling the MovieImportSetAuxiliaryData function. The MovieImportSetChunkSize function allows applications to control the chunk size in the new media. Applications can inform you that the source data came from the scrap by calling your MovieImportSetFromScrap function.
Applications can specify a progress function for use by your component by calling the MovieImportSetProgressProc function.
Applications can instruct your component to display its user dialog box by calling the MovieImportDoUserDialog function.
The MovieImportSetDuration function allows an application to control the duration of the data that your component pastes into the target movie.
pascal ComponentResult MovieImportSetDuration
(MovieImportComponent ci,
TimeValue duration);
Applications may use the MovieImportSetDuration function to set the duration of the data to be pasted by your movie data import component. This duration is expressed in the movie's time scale.
If your component supports paste operations (that is, your component allows the application to set the movieImportInParallel flag to 1 with the MovieImportHandle or MovieImportFile function), then you must support this function. If an application calls this function and sets a duration limit, you must abide by that limit. This function is not valid for insert operations (where the movieImportInParallel flag is set to 0).
The MovieImportSetSampleDuration function allows an application to set the sample duration for new samples to be created with your component.
pascal ComponentResult MovieImportSetSampleDuration
(MovieImportComponent ci,
TimeValue duration,
TimeScale scale);
The MovieImportSetSampleDescription function allows an application to provide a sample description to your movie data import component.
pascal ComponentResult MovieImportSetSampleDescription
(MovieImportComponent ci,
SampleDescriptionHandle desc,
OSType mediaType);
Applications may use the MovieImportSetSampleDescription function to supply a sample description to your movie data import component. This can be useful in cases where your component must transform the data before adding it to the movie's media. For example, your component may be responsible for adding image data to a movie. In this case, you may allow applications to specify image-compression parameters by supplying a formatted image description structure.
The MovieImportSetMediaFile function allows an application to specify a media file that is to receive the imported movie data.
pascal ComponentResult MovieImportSetMediaFile
(MovieImportComponent ci,
AliasHandle alias);
Applications may use the MovieImportSetMediaFile function to specify a destination media file for imported movie data. By default, your movie data import component should add new data to an existing media file that is associated with the movie. However, you may choose to allow applications to specify an alternative destination file. This can be useful when your component is importing data into a new track. In this case, the application can use this function to tell your component where the media's data should reside.
The MovieImportSetDimensions function allows an application to specify a new track's spatial dimensions.
pascal ComponentResult MovieImportSetDimensions
(MovieImportComponent ci, Fixed width,
Fixed height);
Applications may use this function to specify the spatial dimensions of a new track. Although your movie data import component may not change the spatial characteristics of an existing track, if you are importing image data into a new track, you may choose to allow applications to specify the spatial characteristics of the new track.
If you want to change the track's matrix, use the Movie Toolbox's SetTrackMatrix function after performing the import operation.
The MovieImportSetChunkSize function allows an application to specify the amount of data your component works with at a time.
pascal ComponentResult MovieImportSetChunkSize
(MovieImportComponent ci,
long chunkSize);
The chunk size controls the amount of data in each of a media's data chunks (for more information about data chunks in a media, see the chapter "QuickTime Movie Format" in Inside Macintosh: QuickTime ). Generally, your component should determine a reasonable default chunk size, based on the type of data you are importing. However, you may choose to allow applications to override your default value--this can be especially useful for sound data, where the chunk size affects the quality of sound playback.
The MovieImportSetProgressProc function allows an application to assign a movie progress function.
pascal ComponentResult MovieImportSetProgressProc
(MovieImportComponent ci,
MovieProgressUPP proc,
long refcon);
Some data import operations may be time consuming, and application developers may therefore choose to display progress information to the user. Your component provides this information to an application's progress function. As your component processes an import request, you should call the progress function occasionally in order to report on the progress of the operation. Use an operation code value of progressOpImportMovie . The application can then present this information to the user.
These progress functions must support the same interface as Movie Toolbox progress functions. That interface is discussed in the chapter "Movie Toolbox" in Inside Macintosh: QuickTime . Note that this interface not only allows you to report progress to the application, but also allows the application to cancel the request.
The MovieImportSetAuxiliaryData function allows an application to provide additional data to your component. Your component can then use this data during the data import process.
pascal ComponentResult MovieImportSetAuxiliaryData
(MovieImportComponent ci,
Handle data,
OSType handleType);
The MovieImportSetAuxiliaryData function allows your component to accept additional data for use during the data import process. Your component may use this data in any way that is appropriate for a given import operation. For example, if your component imports data stored in 'TEXT' handles, you might choose to accept style information for that text. An application could provide that style information in a 'styl' handle supplied to your component by calling this function.
Your component should expect the application to call this function before the import process begins.
The MovieImportSetFromScrap function allows an application to indicate that the source data resides on the scrap.
pascal ComponentResult MovieImportSetFromScrap
(MovieImportComponent ci,
Boolean fromScrap);
The MovieImportSetFromScrap function allows an application to indicate that the data to be imported originated on the scrap. In some cases, your component may be able to use this information during the import process. For example, you may establish the convention that additional data that is pertinent to an import operation should be stored on the scrap along with the data to be imported. Your component can then look in the scrap for the additional data.
The MovieImportDoUserDialog function allows an application to request that your component display its user dialog box.
pascal ComponentResult MovieImportDoUserDialog
(MovieImportComponent ci,
const FSSpec *theFile,
Handle theData, Boolean *canceled);
Your movie data import component may support a user dialog box that allows the user to configure an import operation. For components that support such a dialog box, the MovieImportDoUserDialog function allows an application to tell you when to display the dialog box to the user.
If your component supports a user dialog box, be sure to set the hasMovieImportUserInterface flag in your component's componentFlags field.
| Previous | Chapter contents | Chapter top | Section top | Next |